Feature/mnaveau/doc by MaximilienNaveau · Pull Request #307 · agimus-project/agimus-controller

MaximilienNaveau · 2026-02-20T16:33:56Z

@Kotochleb @ahaffemayer @MaximeSabbah @petrikvladimir : I through the base of the documentation of the different costs. Please review the MAth in case of error. This was AI generated very quickly.

@nim65s I through the base of the nix build of the agimus_controller_doc.

@petrikvladimir please review the PR and tell me if this documentation is enough for you or if you need more details in the API usage.

…agimus-controller-doc

MaximilienNaveau · 2026-03-20T14:38:59Z

@Mergifyio rebase

mergify · 2026-03-20T14:39:22Z

rebase

☑️ Nothing to do, the required conditions are not met

Details

-conflict [📌 rebase requirement]
-closed [📌 rebase requirement]
queue-position = -1 [📌 rebase requirement]
any of:
- #commits-behind > 0 [📌 rebase requirement]
- -linear-history [📌 rebase requirement]

Copilot

Pull request overview

This PR introduces a new Sphinx documentation package for agimus_controller, wires it into the Nix flake as a buildable derivation, and adds extensive in-code docstrings to the OCP modules to support API generation.

Changes:

Add a new agimus_controller_doc/ documentation package (Sphinx config, markdown sources, autosummary/autodoc pages, CLI helper).
Add a Nix derivation and flake output to build and publish HTML docs.
Add/expand docstrings in ocp_croco_generic.py and ocp_croco_generic_force_feedback.py to improve generated API documentation; update ROS test dependencies.

Reviewed changes

Copilot reviewed 30 out of 30 changed files in this pull request and generated 13 comments.

Show a summary per file

File	Description
flake.nix	Exposes `agimus-controller-doc` as a flake package output.
agimus_controller_doc/pyproject.toml	Defines Poetry package for docs build tooling and dependencies.
agimus_controller_doc/docs/requirements.txt	Provides pip-style requirements for building docs.
agimus_controller_doc/docs/index.md	Adds Sphinx docs landing page with toctree.
agimus_controller_doc/docs/general/usage.md	Adds a brief usage page and YAML snippet example.
agimus_controller_doc/docs/conf.py	Adds Sphinx configuration (extensions, sys.path handling).
agimus_controller_doc/docs/api/ocp_croco_generic.md	Adds a module overview page and `automodule` API extraction.
agimus_controller_doc/docs/api/index.md	Adds API index toctree for autosummary/autoclass pages.
agimus_controller_doc/docs/api/ResidualModelState.md	Autoclass stub page for `ResidualModelState`.
agimus_controller_doc/docs/api/ResidualModelControl.md	Autoclass stub page for `ResidualModelControl`.
agimus_controller_doc/docs/api/ResidualModelControlGrav.md	Autoclass stub page for `ResidualModelControlGrav`.
agimus_controller_doc/docs/api/ResidualModelFramePlacement.md	Autoclass stub page for `ResidualModelFramePlacement`.
agimus_controller_doc/docs/api/ResidualModelFrameTranslation.md	Autoclass stub page for `ResidualModelFrameTranslation`.
agimus_controller_doc/docs/api/ResidualModelFrameRotation.md	Autoclass stub page for `ResidualModelFrameRotation`.
agimus_controller_doc/docs/api/ResidualModelFrameVelocity.md	Autoclass stub page for `ResidualModelFrameVelocity`.
agimus_controller_doc/docs/api/ResidualDistanceCollision.md	Autoclass stub page for `ResidualDistanceCollision`.
agimus_controller_doc/docs/api/ResidualDistanceCollision2.md	Autoclass stub page for `ResidualDistanceCollision2`.
agimus_controller_doc/docs/api/ActivationModelWeightedQuad.md	Autoclass stub page for `ActivationModelWeightedQuad`.
agimus_controller_doc/docs/api/ActivationModelExp.md	Autoclass stub page for `ActivationModelExp`.
agimus_controller_doc/docs/api/ActivationModelQuadExp.md	Autoclass stub page for `ActivationModelQuadExp`.
agimus_controller_doc/docs/api/CostModelResidual.md	Autoclass stub page for `CostModelResidual`.
agimus_controller_doc/docs/api/CostModelSumItem.md	Autoclass stub page for `CostModelSumItem`.
agimus_controller_doc/docs/_static/.gitkeep	Ensures `_static/` is tracked in git.
agimus_controller_doc/default.nix	Adds a Nix derivation that builds Sphinx HTML docs.
agimus_controller_doc/agimus_controller_doc/cli.py	Adds a CLI entrypoint to build docs via Sphinx.
agimus_controller_doc/agimus_controller_doc/init.py	Initializes the docs helper Python package.
agimus_controller_doc/README.md	Documents ways to build/host the docs (venv, Nix, Poetry).
agimus_controller/package.xml	Adds `tiago_robot` as a test dependency.
agimus_controller/agimus_controller/ocp/ocp_croco_generic_force_feedback.py	Adds module/class documentation for force-feedback OCP components.
agimus_controller/agimus_controller/ocp/ocp_croco_generic.py	Adds module/class documentation for generic OCP dataclass builders and models.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-20T14:44:11Z

 class ActivationModelWeightedQuad(ActivationModel):
    class_: T.ClassVar[str] = "ActivationModelWeightedQuad"
    weights: T.Union[None, float, npt.NDArray[np.float64]] = None
+    """Weighted quadratic activation.
+


The triple-quoted string here is not a class docstring because it appears after assignments (class_ / weights). It becomes a no-op string literal at runtime and won’t show up in generated docs. Move this text to be the first statement in the class body (immediately after the class ...: line) or convert it into a real comment/docstring structure.

Copilot · 2026-03-20T14:44:12Z

 class ActivationModelExp(ActivationModel):
    class_: T.ClassVar[str] = "ActivationModelExp"
    alpha: float = 1.0
    exponent: int = 1
+    """Exponential-like activation.


This triple-quoted block is not a class docstring because it is not the first statement in the class body (it comes after attribute assignments). It becomes an unused string literal and won’t show up in autodoc/help(). Move it to immediately after class ActivationModelExp...:.

Copilot · 2026-03-20T14:44:12Z

    class_: T.ClassVar[str] = "DifferentialActionModelFreeFwdDynamics"
    costs: T.List[CostModelSumItem]
    constraints: T.List[ConstraintListItem] = dataclasses.field(default_factory=list)

+    """Differential action model using free forward dynamics.


This triple-quoted block is not a docstring (it appears after field annotations), so it will be ignored by autodoc and kept as an unused string literal. Move it to be the first statement in the class body.

Copilot · 2026-03-20T14:44:13Z

        return iam

+    """Integrated action model that wraps a soft-contact augmented DAM.
+
+    This wrapper integrates the augmented differential action model using the


This triple-quoted block is not a docstring for IAMSoftContactAugmented (it is placed after methods). It will be ignored by autodoc and kept as an unused string literal. Move it to immediately after the class IAMSoftContactAugmented: line.

Copilot · 2026-03-20T14:44:14Z

+2. Build HTML:
+
+```bash
+make html
+# Output is in _build/html
+```


The README suggests make html, but there is no docs/Makefile in this package, so this command will fail. Either add the standard Sphinx Makefile under docs/ or change the instructions to use sphinx-build -b html docs docs/_build/html (or the Poetry/Nix commands below).

Copilot · 2026-03-20T14:44:15Z

+
+# Compute and add repository root to sys.path so autodoc can import
+# the `agimus_controller` package regardless of current working dir.
+ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))


ROOT is described as the repository root, but ../../ from agimus_controller_doc/docs/conf.py resolves to agimus_controller_doc/, not the actual repo root. If agimus_controller is not installed in the environment, autodoc imports will fail because the sibling agimus_controller/ package won’t be on sys.path. Consider adjusting the path (e.g., one more .. or explicitly adding ../agimus_controller) or updating the comment to reflect the intended build assumptions (Nix/Poetry-installed package).

Suggested change

ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))

ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", ".."))

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

MaximilienNaveau added 7 commits February 20, 2026 16:14

Add agimus-controller-doc Nix derivation and expose package in flake

dae6afd

Fix autosummary entries to use fully-qualified names

78412c6

Add per-class API pages to satisfy autosummary links

8711cfe

Replace autosummary with explicit per-class links for ocp_croco_generic

9a68351

Revert missed commits

b621bda

Remove extra config.py try to add agimus-controller as dependency of …

e56d319

…agimus-controller-doc

Fix the build of the documentation

6ad58c1

MaximilienNaveau requested review from Kotochleb, MaximeSabbah, ahaffemayer, Copilot, nim65s and petrikvladimir and removed request for Copilot February 20, 2026 16:33

Copilot started reviewing on behalf of MaximilienNaveau February 20, 2026 16:34 View session

MaximilienNaveau commented Mar 20, 2026

View reviewed changes

Comment thread agimus_controller_doc/default.nix Outdated

Remove the input fetchFromGithub in the local nix

da836dd

Copilot AI review requested due to automatic review settings March 20, 2026 14:38

Copilot started reviewing on behalf of MaximilienNaveau March 20, 2026 14:38 View session

Merge branch 'humble-devel' into feature/mnaveau/doc

8ef78bf

Copilot AI reviewed Mar 20, 2026

View reviewed changes

MaximilienNaveau and others added 4 commits March 20, 2026 16:27

Update agimus_controller_doc/default.nix

ba9e959

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update agimus_controller_doc/README.md

b784a0e

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update agimus_controller_doc/agimus_controller_doc/cli.py

8bf857e

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

try to build the doc with nix

d8697f3

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Feature/mnaveau/doc#307

Feature/mnaveau/doc#307
MaximilienNaveau wants to merge 13 commits into
agimus-project:humble-develfrom
MaximilienNaveau:feature/mnaveau/doc

MaximilienNaveau commented Feb 20, 2026

Uh oh!

Uh oh!

MaximilienNaveau commented Mar 20, 2026

Uh oh!

mergify Bot commented Mar 20, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 20, 2026

Uh oh!

Copilot AI Mar 20, 2026

Uh oh!

Copilot AI Mar 20, 2026

Uh oh!

Uh oh!

Uh oh!

Copilot AI Mar 20, 2026

Uh oh!

Uh oh!

Copilot AI Mar 20, 2026

Uh oh!

Uh oh!

Copilot AI Mar 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
	ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", ".."))

Uh oh!

Conversation

MaximilienNaveau commented Feb 20, 2026

Uh oh!

Uh oh!

MaximilienNaveau commented Mar 20, 2026

Uh oh!

mergify Bot commented Mar 20, 2026

☑️ Nothing to do, the required conditions are not met

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants